<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../../assets/docs.css" rel="stylesheet" type="text/css" media="screen" />
<title>MooTools 1.3 Documentation - Drag/Sortables</title>
</head>

<body>
  <div class="doc">
    <div class="methods">
      <h4 class="menu-item"><a href="#Sortables">Sortables</a></h4>
      <div class="menu-item"><a href="#Sortables:attach">attach</a></div>
      <div class="menu-item"><a href="#Sortables:detach">detach</a></div>
      <div class="menu-item"><a href="#Sortables:addItems">addItems</a></div>
      <div class="menu-item"><a href="#Sortables:removeItems">removeItems</a></div>
      <div class="menu-item"><a href="#Sortables:addLists">addLists</a></div>
      <div class="menu-item"><a href="#Sortables:removeLists">removeLists</a></div>
      <div class="menu-item"><a href="#Sortables:serialize">serialize</a></div>
    </div>
    <div class="l-border r-border span-15 content">
      <h1 id="Sortables"><a href="#Sortables">Class: Sortables</a></h1>
      <p class="description">Creates an interface for drag and drop sorting of a list or lists.</p>
      <h3>Arguments</h3>
      <ol>
        <li>list - (<em>mixed</em>) required, the list or lists that will become sortable.
          <ul>
            <li>This argument can be an <a href="../../../docs/core/Element/Element.html">Element</a>, an array of <a href="../../../docs/core/Element/Element.html#Elements">Elements</a>, or a selector. When a single list (or id) is passed, that list will be sortable only with itself.</li>
            <li>To enable sorting between lists, one or more lists or id's must be passed using an array or a selector. See Examples below.</li>
          </ul>
        </li>
        <li>options - (<em>object</em>) See options and events below.</li>
      </ol>
      <h3>Options</h3>
      <ul>
        <li>constrain - (<em>boolean</em>: defaults to <em>false</em>) Whether or not to constrain the element being dragged to its parent element.</li>
        <li>clone - (<em>mixed</em>: defaults to <em>false</em>) Whether or not to display a copy of the actual element under the cursor while dragging. May also be used as a function which will return an element to be used as the clone.  The function will receive the mousedown event, the element, and the list as arguments.</li>
        <li>handle - (<em>string</em>: defaults to <em>false</em>) A selector to select an element inside each sortable item to be used as the handle for sorting that item.  If no match is found, the element is used as its own handle.</li>
        <li>opacity - (<em>integer</em>: defaults to <em>1</em>) Opacity of the place holding element</li>
        <li>revert - (<em>mixed</em>: defaults to <em>false</em>) Whether or not to use an effect to slide the element into its final location after sorting. If you pass an object it will be used as additional options for the revert effect.</li>
        <li>snap - (<em>integer</em>; defaults to <em>4</em>) The number of pixels the element must be dragged for sorting to begin.</li>
        <li>preventDefault - (<em>boolean</em>; defaults to <em>false</em>) if true, then dragging a link or image that is in a sortable element will work (otherwise the browser may attempt to drag the element out of the browser - to your desktop or bookmark bar for example).</li>
      </ul>
      <h3>Events</h3>
      <h4>start</h4>
      <p>Fired when the item starts dragging.</p>
      <h5>Signature</h5>
      <pre class="javascript">onStart<span class="br0">(</span>element, clone<span class="br0">)</span>
</pre>
      <h5>Arguments</h5>
      <ol>
        <li>element - (<em>element</em>) The Element being sorted.</li>
        <li>clone - (<em>element</em>) The clone of the Element.</li>
      </ol>
      <h4>sort</h4>
      <p>Fired when the item is inserted into a new place in one of the lists.</p>
      <h5>Signature</h5>
      <pre class="javascript">onSort<span class="br0">(</span>element, clone<span class="br0">)</span>
</pre>
      <h5>Arguments</h5>
      <ol>
        <li>element - (<em>element</em>) The Element being sorted.</li>
        <li>clone - (<em>element</em>) The clone of the Element.</li>
      </ol>
      <h4>complete</h4>
      <p>Fired when the item ends dragging. Note: fires even if the sort has not changed.</p>
      <h5>Signature</h5>
      <pre class="javascript">onComplete<span class="br0">(</span>element<span class="br0">)</span>
</pre>
      <h5>Arguments</h5>
      <ol>
        <li>element - (<em>element</em>) The Element being sorted.</li>
      </ol>
      <h3>Examples</h3>
      <pre class="javascript"><span class="kw2">var</span> mySortables = <span class="kw2">new</span> Sortables<span class="br0">(</span><span class="st0">'list-1'</span>, <span class="br0">{</span>
    revert: <span class="br0">{</span> duration: <span class="nu0">500</span>, transition: <span class="st0">'elastic:out'</span> <span class="br0">}</span>

<span class="br0">}</span><span class="br0">)</span>;
<span class="co1">//creates a new Sortable instance over the list with id 'list-1' with some</span>
<span class="co1">//extra options for the revert effect</span>
&nbsp;
<span class="kw2">var</span> mySortables = <span class="kw2">new</span> Sortables<span class="br0">(</span><span class="st0">'#list-1, #list-2'</span>, <span class="br0">{</span>

    constrain: <span class="kw2">true</span>,
    clone: <span class="kw2">false</span>,
    revert: <span class="kw2">true</span>
<span class="br0">}</span><span class="br0">)</span>;
<span class="co1">//creates a new Sortable instance allowing the sorting of the lists with</span>
<span class="co1">//ids 'list-1' and 'list-2' with extra options since constrain was set to</span>
<span class="co1">//true, the items will not be able to be dragged from one list to the other</span>

&nbsp;
<span class="kw2">var</span> mySortables = <span class="kw2">new</span> Sortables<span class="br0">(</span><span class="st0">'#list-1, #list-2, #list-3'</span><span class="br0">)</span>;
<span class="co1">//creates a new Sortable instance allowing sorting between the lists with</span>
<span class="co1">//ids 'list-1', 'list-2, and 'list-3'</span>
</pre>
      <h2 id="Sortables:attach"><a href="#Sortables:attach">Sortables Method: attach</a></h2>
      <p class="description">Attaches the mouse listener to all the handles, enabling sorting.</p>
      <h3>Syntax</h3>
      <pre class="javascript">mySortables.<span class="me1">attach</span><span class="br0">(</span><span class="br0">)</span>;
</pre>
      <h3>Returns</h3>
      <ul>
        <li>(<em>object</em>) This Sortables instance.</li>
      </ul>
      <h2 id="Sortables:detach"><a href="#Sortables:detach">Sortables Method: detach</a></h2>
      <p class="description">Detaches the mouse listener from all the handles, disabling sorting.</p>
      <h3>Syntax</h3>
      <pre class="javascript">mySortables.<span class="me1">detach</span><span class="br0">(</span><span class="br0">)</span>;

</pre>
      <h3>Returns</h3>
      <ul>
        <li>(<em>object</em>) This Sortables instance.</li>
      </ul>
      <h2 id="Sortables:addItems"><a href="#Sortables:addItems">Sortables Method: addItems</a></h2>
      <p class="description">Allows one or more items to be added to an existing Sortables instance.</p>
      <h3>Syntax</h3>
      <pre class="javascript">mySortables.<span class="me1">addItems</span><span class="br0">(</span>item1<span class="br0">[</span>, item2<span class="br0">[</span>, item3<span class="br0">[</span>, ...<span class="br0">]</span><span class="br0">]</span><span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>Arguments</h3>
      <ol>
        <li>items - (<em>mixed</em>) Since Array.flatten is used on the arguments, a single element, several elements, an array of elements, or any combination thereof may be passed to this method.</li>
      </ol>
      <h3>Returns</h3>
      <ul>
        <li>(<em>object</em>) This Sortables instance.</li>
      </ul>
      <h3>Examples</h3>
      <pre class="javascript"><span class="kw2">var</span> mySortables = <span class="kw2">new</span> Sortables<span class="br0">(</span><span class="st0">'#list1, #list2'</span><span class="br0">)</span>;
&nbsp;
<span class="kw2">var</span> element1 = <span class="kw2">new</span> Element<span class="br0">(</span><span class="st0">'div'</span><span class="br0">)</span>;

<span class="kw2">var</span> element2 = <span class="kw2">new</span> Element<span class="br0">(</span><span class="st0">'div'</span><span class="br0">)</span>;
<span class="kw2">var</span> element3 = <span class="kw2">new</span> Element<span class="br0">(</span><span class="st0">'div'</span><span class="br0">)</span>;

&nbsp;
$<span class="br0">(</span><span class="st0">'list1'</span><span class="br0">)</span>.<span class="me1">adopt</span><span class="br0">(</span>element1<span class="br0">)</span>;
$<span class="br0">(</span><span class="st0">'list2'</span><span class="br0">)</span>.<span class="me1">adopt</span><span class="br0">(</span>element2, element3<span class="br0">)</span>;
mySortables.<span class="me1">addItems</span><span class="br0">(</span>element1, element2, element3<span class="br0">)</span>;

</pre>
      <h3>Notes</h3>
      <ul>
        <li>The items will not be injected into the list automatically as the sortable instance could have many lists.</li>
        <li>First inject the elements into the proper list, then call addItems on them.</li>
      </ul>
      <h3>See Also</h3>
      <ul>
        <li> <a href="#Sortables:removeItems">Sortables:removeItems</a>, <a href="#Sortables:addLists">Sortables:addLists</a> </li>
      </ul>
      <h2 id="Sortables:removeItems"><a href="#Sortables:removeItems">Sortables Method: removeItems</a></h2>
      <p class="description">Allows one or more items to be removed from an existing Sortables instance.</p>
      <h3>Syntax</h3>
      <pre class="javascript">mySortables.<span class="me1">removeItems</span><span class="br0">(</span>item1<span class="br0">[</span>, item2<span class="br0">[</span>, item3<span class="br0">[</span>, ...<span class="br0">]</span><span class="br0">]</span><span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>Arguments</h3>
      <ol>
        <li>items - (<em>mixed</em>) Since Array.flatten is used on the arguments, a single element, several elements, an array of elements, or any combination thereof may be passed to this method.</li>
      </ol>
      <h3>Returns</h3>
      <ul>
        <li>(<em>Elements</em>) An Elements collection of all the elements that were removed.</li>
      </ul>
      <h3>Examples</h3>
      <pre class="javascript"><span class="kw2">var</span> mySortables = <span class="kw2">new</span> Sortables<span class="br0">(</span><span class="st0">'#list1, #list2'</span><span class="br0">)</span>;
&nbsp;
<span class="kw2">var</span> element1 = $<span class="br0">(</span><span class="st0">'list1'</span><span class="br0">)</span>.<span class="me1">getFirst</span><span class="br0">(</span><span class="br0">)</span>;

<span class="kw2">var</span> element2 = $<span class="br0">(</span><span class="st0">'list2'</span><span class="br0">)</span>.<span class="me1">getLast</span><span class="br0">(</span><span class="br0">)</span>;
&nbsp;
mySortables.<span class="me1">removeItems</span><span class="br0">(</span>element1, element2<span class="br0">)</span>.<span class="me1">destroy</span><span class="br0">(</span><span class="br0">)</span>; <span class="co1">//the elements will be removed and destroyed</span>

</pre>
      <h3>Notes</h3>
      <ul>
        <li>The items will not be removed from the list automatically, they will just no longer be sortable.</li>
        <li>First call removeItems on the items, and then remove them from their list containers, or destroy them.</li>
      </ul>
      <h3>See Also</h3>
      <ul>
        <li> <a href="#Sortables:addItems">Sortables:addItems</a>, <a href="#Sortables:removeLists">Sortables:removeLists</a> </li>
      </ul>
      <h2 id="Sortables:addLists"><a href="#Sortables:addLists">Sortables Method: addLists</a></h2>
      <p class="description">Allows one or more entire lists to be added to an existing Sortables instance, allowing sorting between the new and old lists.</p>
      <h3>Syntax</h3>
      <pre class="javascript">mySortables.<span class="me1">addLists</span><span class="br0">(</span>list1<span class="br0">[</span>, list2<span class="br0">[</span>, list3<span class="br0">[</span>, ...<span class="br0">]</span><span class="br0">]</span><span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>Arguments</h3>
      <ol>
        <li>lists - (<em>mixed</em>) Since Array.flatten is used on the arguments, a single element, several elements, an array of elements, or any combination thereof may be passed to this method.</li>
      </ol>
      <h3>Returns</h3>
      <ul>
        <li>(<em>object</em>) This Sortables instance.</li>
      </ul>
      <h3>Examples</h3>
      <pre class="javascript"><span class="kw2">var</span> mySortables = <span class="kw2">new</span> Sortables<span class="br0">(</span><span class="st0">'list1'</span><span class="br0">)</span>;
mySortables.<span class="me1">addLists</span><span class="br0">(</span>$<span class="br0">(</span><span class="st0">'list2'</span><span class="br0">)</span><span class="br0">)</span>;

</pre>
      <h3>Notes</h3>
      <ul>
        <li>More complicated usage of this method will allow you to do things like one-directional sorting.</li>
      </ul>
      <h3>See Also</h3>
      <ul>
        <li> <a href="#Sortables:removeLists">Sortables:removeLists</a>, <a href="#Sortables:addItems">Sortables:addItems</a> </li>
      </ul>
      <h2 id="Sortables:removeLists"><a href="#Sortables:removeLists">Sortables Method: removeLists</a></h2>
      <p class="description">Allows one or more entire lists to be removed from an existing Sortables instance, preventing sorting between the lists.</p>
      <h3>Syntax</h3>
      <pre class="javascript">mySortables.<span class="me1">removeLists</span><span class="br0">(</span>list1<span class="br0">[</span>, list2<span class="br0">[</span>, list3<span class="br0">[</span>, ...<span class="br0">]</span><span class="br0">]</span><span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>Arguments</h3>
      <ol>
        <li>lists - (<em>mixed</em>) Since Array.flatten is used on the arguments, a single element, several elements, an array of elements, or any combination thereof may be passed to this method.</li>
      </ol>
      <h3>Returns</h3>
      <ul>
        <li>(<em>Elements</em>) An Elements collection of all the lists that were removed.</li>
      </ul>
      <h3>Examples</h3>
      <pre class="javascript"><span class="kw2">var</span> mySortables = <span class="kw2">new</span> Sortables<span class="br0">(</span><span class="st0">'#list1, #list2'</span><span class="br0">)</span>;
mySortables.<span class="me1">removeLists</span><span class="br0">(</span>$<span class="br0">(</span><span class="st0">'list2'</span><span class="br0">)</span><span class="br0">)</span>;

</pre>
      <h3>See Also</h3>
      <ul>
        <li> <a href="#Sortables:addLists">Sortables:addLists</a>, <a href="#Sortables:removeItems">Sortables:removeItems</a> </li>
      </ul>
      <h2 id="Sortables:serialize"><a href="#Sortables:serialize">Sortables Method: serialize</a></h2>
      <p class="description">Function to get the order of the elements in the lists of this sortables instance.
        For each list, an array containing the order of the elements will be returned.
        If more than one list is being used, all lists will be serialized and returned in an array.</p>
      <h3>Arguments</h3>
      <ol>
        <li>index    - (<em>mixed</em>, optional) An integer or boolean false. index of the list to serialize. Omit or pass false to serialize all lists.</li>
        <li>modifier - (<em>function</em>, optional) A function to override the default output of the sortables.  See Examples below</li>
      </ol>
      <h3>Examples</h3>
      <pre class="javascript">mySortables.<span class="me1">serialize</span><span class="br0">(</span><span class="nu0">1</span><span class="br0">)</span>;
<span class="co1">//returns the second list serialized (remember, arrays are 0 based...);</span>
<span class="co1">//['item_1-1', 'item_1-2', 'item_1-3']</span>
&nbsp;
mySortables.<span class="me1">serialize</span><span class="br0">(</span><span class="br0">)</span>;
<span class="co1">//returns a nested array of all lists serialized, or if only one list exists, that lists order</span>

<span class="coMULTI">/*[['item_1-1', 'item_1-2', 'item_1-3'],
  ['item_2-1', 'item_2-2', 'item_2-3'],
  ['item_3-1', 'item_3-2', 'item_3-3']]*/</span>
&nbsp;
mySortables.<span class="me1">serialize</span><span class="br0">(</span><span class="nu0">2</span>, <span class="kw2">function</span><span class="br0">(</span>element, index<span class="br0">)</span><span class="br0">{</span>

    <span class="kw1">return</span> element.<span class="me1">getProperty</span><span class="br0">(</span><span class="st0">'id'</span><span class="br0">)</span>.<span class="me1">replace</span><span class="br0">(</span><span class="st0">'item_'</span>,<span class="st0">''</span><span class="br0">)</span> + <span class="st0">'='</span> + index;

<span class="br0">}</span><span class="br0">)</span>.<span class="me1">join</span><span class="br0">(</span><span class="st0">'&amp;'</span><span class="br0">)</span>;
<span class="co1">//joins the array with a '&amp;' to return a string of the formatted ids of all the elmements in list 3,with their position</span>
<span class="co1">//'3-0=0&amp;3-1=1&amp;3-2=2'</span>
</pre>
    </div>
  </div>
<script type="text/javascript" src="../../../assets/mootools-core-1.3.js"></script>
<script type="text/javascript" src="../../../assets/mootools-more-smoothscroll.js"></script>
<script type="text/javascript" src="../../../assets/doc-assist.js"></script>
</body>
</html>
